Skip to main content
This guide covers the most frequently encountered issues during development and their solutions.

​
Port Conflicts

Error Message:
Web server failed to start. Port 8080 was already in use.
Solution:
  1. Find the process using port 8080:
lsof -i :8080
# or on Windows
netstat -ano | findstr :8080
  1. Kill the process:
kill -9 <PID>
# or on Windows
taskkill /PID <PID> /F
  1. Or change the backend port in application.properties:
server.port=8081
If you change the backend port, update the frontend API calls accordingly.
Error Message:
Port 5173 is in use, trying another one...
Solution:
  1. Find and kill the process:
lsof -i :5173
kill -9 <PID>
  1. Or let Vite use a different port automatically (it will suggest 5174, 5175, etc.)
  2. Or specify a custom port in vite.config.ts: 
export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000
  }
})
If you change the frontend port, update the CORS configuration in SecurityConfig.java to include the new origin.
Error Message:
Can't connect to MySQL server on 'localhost:3306'
Solution:
  1. Check if MySQL is running:
sudo systemctl status mysql
# or on macOS
mysql.server status
  1. If another MySQL instance is running on 3306, either:
    • Stop that instance
    • Or change the database port in application.properties:
spring.datasource.url=jdbc:mysql://localhost:3307/apiIquea?createDatabaseIfNotExist=true
  1. Restart your MySQL server:
sudo systemctl restart mysql
# or on macOS
mysql.server restart

​
Dependency Issues

Common Errors:
npm ERR! code ENOENT
npm ERR! syscall open
Solutions:
  1. Clear npm cache:
cd Iquea_front
npm cache clean --force
  1. Delete node_modules and package-lock.json:
rm -rf node_modules package-lock.json
npm install
  1. If using a different Node version, use nvm:
nvm install 18
nvm use 18
npm install
  1. Check for permission issues:
sudo chown -R $USER:$USER node_modules
The project uses Vite 7.3.1 and React 19.2.0. Ensure you have Node.js 18+ installed.
Error Message:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin
Solutions:
  1. Clean and rebuild:
cd Iqüea_back
mvn clean install
  1. Check Java version (project requires Java 21):
java -version
  1. If wrong version, install Java 21:
# Using SDKMAN
sdk install java 21.0.1-open
sdk use java 21.0.1-open
  1. Clear Maven cache:
rm -rf ~/.m2/repository
mvn clean install
  1. Skip tests if they’re failing:
mvn clean install -DskipTests
The project uses MapStruct 1.6.0 and Lombok 1.18.38. Ensure your IDE has annotation processing enabled.

​
Authentication Issues

Error in Browser Console:
401 Unauthorized
JWT token has expired
Explanation:Tokens expire after 24 hours (configured in JwtUtil.java:17).Solutions:
  1. Log out and log back in to get a new token
  2. For development, increase token expiration in JwtUtil.java: 
private static final long EXPIRATION_MS = 86400000L; // 24 hours
// Change to 7 days for development:
private static final long EXPIRATION_MS = 604800000L; // 7 days
  1. Implement token refresh mechanism in your frontend
  2. Check token in browser DevTools: 
localStorage.getItem('token')
Tokens are stored in localStorage. Clear storage if you encounter persistent issues:
localStorage.clear()
Error Message:
JWT signature does not match
Malformed JWT token
Solutions:
  1. Clear localStorage in browser:
localStorage.clear()
location.reload()
  1. Verify the token format:
    • Should have 3 parts separated by dots: header.payload.signature
  2. Check if the secret key matches between environments:
    • Located in JwtUtil.java:16
  3. Ensure token is sent with correct header: 
headers: {
  'Authorization': `Bearer ${token}`
}

​
Frontend-Backend Connection

Error in Browser Console:
GET http://localhost:8080/api/productos net::ERR_CONNECTION_REFUSED
Solutions:
  1. Verify backend is running:
curl http://localhost:8080/api/productos
  1. Check backend port in application.properties:4:
server.port=8080
  1. Verify API base URL in frontend code
  2. Check firewall settings: 
# Linux
sudo ufw allow 8080

# Windows
# Add port 8080 to Windows Firewall exceptions
  1. Ensure MySQL is running (backend won’t start without it):
sudo systemctl start mysql
Error:
404 Not Found
Solutions:
  1. Check the API endpoint path:
    • Authentication: /api/auth/**
    • Products: /api/productos/**
    • Categories: /api/categorias/**
  2. Verify controller mapping in backend code
  3. Check for typos (especially with special characters like ü in “Iqüea”)
  4. Look at backend console logs for actual registered endpoints: 
Mapped "{[/api/productos]}"

​
Development Server Issues

Problem: Changes to React components don’t reflect in the browser.Solutions:
  1. Check if Fast Refresh is enabled in vite.config.ts:
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()]
})
  1. Restart the dev server:
ctrl+c
npm run dev
  1. Clear browser cache:
    • Chrome/Edge: Ctrl+Shift+Delete
    • Or hard reload: Ctrl+Shift+R
  2. Check for TypeScript errors: 
npm run lint
  1. Ensure file is saved and within src directory
Problem: Code changes require manual restart.Solutions:
  1. Verify Spring Boot DevTools is in pom.xml (line 79-82):
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-devtools</artifactId>
  <scope>runtime</scope>
  <optional>true</optional>
</dependency>
  1. Enable “Build project automatically” in your IDE:
    • IntelliJ: Settings → Build → Compiler → Build project automatically
    • Eclipse: Project → Build Automatically
  2. For structural changes (new classes, dependencies), restart manually: 
mvn spring-boot:run
DevTools only hot-reloads code changes. Configuration changes in application.properties require a full restart.

​
Additional Resources